<!doctype html>

<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>menu.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
  </script>

  <script src="static/js/doc.js">
  </script>

  <meta charset="utf8">
</head>

<body onload="prettyPrint()">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>

<div class="clear"></div>

<h2><a href="closure_goog_ui_menu.js.html">menu.js</a></h2>

<pre class="prettyprint lang-js">
<a name="line1"></a>// Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
<a name="line2"></a>// you may not use this file except in compliance with the License.
<a name="line3"></a>// You may obtain a copy of the License at
<a name="line4"></a>//
<a name="line5"></a>//     http://www.apache.org/licenses/LICENSE-2.0
<a name="line6"></a>//
<a name="line7"></a>// Unless required by applicable law or agreed to in writing, software
<a name="line8"></a>// distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
<a name="line9"></a>// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
<a name="line10"></a>// See the License for the specific language governing permissions and
<a name="line11"></a>// limitations under the License.
<a name="line12"></a>
<a name="line13"></a>// Copyright 2007 Google Inc. All Rights Reserved.
<a name="line14"></a>
<a name="line15"></a>/**
<a name="line16"></a> * @fileoverview A base menu class that supports key and mouse events. The menu
<a name="line17"></a> * can be bound to an existing HTML structure or can generate its own DOM.
<a name="line18"></a> *
<a name="line19"></a> * To decorate, the menu should be bound to an element containing children
<a name="line20"></a> * with the classname &#39;goog-menuitem&#39;.  HRs will be classed as separators.
<a name="line21"></a> *
<a name="line22"></a> * Decorate Example:
<a name="line23"></a> * &lt;div id=&quot;menu&quot; class=&quot;goog-menu&quot; tabIndex=&quot;0&quot;&gt;
<a name="line24"></a> *   &lt;div class=&quot;goog-menuitem&quot;&gt;Google&lt;/div&gt;
<a name="line25"></a> *   &lt;div class=&quot;goog-menuitem&quot;&gt;Yahoo&lt;/div&gt;
<a name="line26"></a> *   &lt;div class=&quot;goog-menuitem&quot;&gt;MSN&lt;/div&gt;
<a name="line27"></a> *   &lt;hr&gt;
<a name="line28"></a> *   &lt;div class=&quot;goog-menuitem&quot;&gt;New...&lt;/div&gt;
<a name="line29"></a> * &lt;/div&gt;
<a name="line30"></a> * &lt;script&gt;
<a name="line31"></a> *
<a name="line32"></a> * var menu = new goog.ui.Menu();
<a name="line33"></a> * menu.decorate(goog.dom.getElement(&#39;menu&#39;));
<a name="line34"></a> *
<a name="line35"></a> * TESTED=FireFox 2.0, IE6, Opera 9, Chrome.
<a name="line36"></a> * TODO: Key handling is flakey in Opera and Chrome
<a name="line37"></a> * TODO: Rename all references of &quot;item&quot; to child since menu is
<a name="line38"></a> * essentially very generic and could, in theory, host a date or color picker.
<a name="line39"></a> *
<a name="line40"></a> * @see ../demos/menu.html
<a name="line41"></a> */
<a name="line42"></a>
<a name="line43"></a>goog.provide(&#39;goog.ui.Menu&#39;);
<a name="line44"></a>goog.provide(&#39;goog.ui.Menu.EventType&#39;);
<a name="line45"></a>
<a name="line46"></a>goog.require(&#39;goog.array&#39;);
<a name="line47"></a>goog.require(&#39;goog.string&#39;);
<a name="line48"></a>goog.require(&#39;goog.style&#39;);
<a name="line49"></a>goog.require(&#39;goog.ui.Component.EventType&#39;);
<a name="line50"></a>goog.require(&#39;goog.ui.Component.State&#39;);
<a name="line51"></a>goog.require(&#39;goog.ui.Container&#39;);
<a name="line52"></a>goog.require(&#39;goog.ui.Container.Orientation&#39;);
<a name="line53"></a>// The following dependencies (MenuItem &amp; MenuSeparator) are impicit.
<a name="line54"></a>// There are no references in the code, but we need to load these
<a name="line55"></a>// classes before goog.ui.Menu.
<a name="line56"></a>goog.require(&#39;goog.ui.MenuItem&#39;);
<a name="line57"></a>goog.require(&#39;goog.ui.MenuRenderer&#39;);
<a name="line58"></a>goog.require(&#39;goog.ui.MenuSeparator&#39;);
<a name="line59"></a>
<a name="line60"></a>
<a name="line61"></a>// TODO: Reverse constructor argument order for consistency.
<a name="line62"></a>/**
<a name="line63"></a> * A basic menu class.
<a name="line64"></a> * @param {goog.dom.DomHelper} opt_domHelper Optional DOM helper.
<a name="line65"></a> * @param {goog.ui.MenuRenderer} opt_renderer Renderer used to render or
<a name="line66"></a> *     decorate the container; defaults to {@link goog.ui.MenuRenderer}.
<a name="line67"></a> * @constructor
<a name="line68"></a> * @extends {goog.ui.Container}
<a name="line69"></a> */
<a name="line70"></a>goog.ui.Menu = function(opt_domHelper, opt_renderer) {
<a name="line71"></a>  goog.ui.Container.call(this, goog.ui.Container.Orientation.VERTICAL,
<a name="line72"></a>      opt_renderer || goog.ui.MenuRenderer.getInstance(), opt_domHelper);
<a name="line73"></a>
<a name="line74"></a>  // Unlike Containers, Menus aren&#39;t keyboard-accessible by default.  This line
<a name="line75"></a>  // preserves backwards compatibility with code that depends on menus not
<a name="line76"></a>  // receiving focus - e.g. {@code goog.ui.MenuButton}.
<a name="line77"></a>  this.setFocusable(false);
<a name="line78"></a>};
<a name="line79"></a>goog.inherits(goog.ui.Menu, goog.ui.Container);
<a name="line80"></a>
<a name="line81"></a>
<a name="line82"></a>// TODO: Remove this and all references to it.
<a name="line83"></a>// Please ensure that BEFORE_SHOW behavior is not disrupted as a result.
<a name="line84"></a>/**
<a name="line85"></a> * Event types dispatched by the menu.
<a name="line86"></a> * @enum {string}
<a name="line87"></a> * @deprecated Use goog.ui.Component.EventType.
<a name="line88"></a> */
<a name="line89"></a>goog.ui.Menu.EventType = {
<a name="line90"></a>  /** Dispatched before the menu becomes visible */
<a name="line91"></a>  BEFORE_SHOW: goog.ui.Component.EventType.BEFORE_SHOW,
<a name="line92"></a>
<a name="line93"></a>  /** Dispatched when the menu is shown */
<a name="line94"></a>  SHOW: goog.ui.Component.EventType.SHOW,
<a name="line95"></a>
<a name="line96"></a>  /** Dispatched before the menu becomes hidden */
<a name="line97"></a>  BEFORE_HIDE: goog.ui.Component.EventType.HIDE,
<a name="line98"></a>
<a name="line99"></a>  /** Dispatched when the menu is hidden */
<a name="line100"></a>  HIDE: goog.ui.Component.EventType.HIDE
<a name="line101"></a>};
<a name="line102"></a>
<a name="line103"></a>
<a name="line104"></a>// TODO: Remove this and all references to it.
<a name="line105"></a>/**
<a name="line106"></a> * CSS class for menus.
<a name="line107"></a> * @type {string}
<a name="line108"></a> * @deprecated Use goog.ui.MenuRenderer.CSS_CLASS.
<a name="line109"></a> */
<a name="line110"></a>goog.ui.Menu.CSS_CLASS = goog.ui.MenuRenderer.CSS_CLASS;
<a name="line111"></a>
<a name="line112"></a>
<a name="line113"></a>/**
<a name="line114"></a> * Whether the menu can move the focus to it&#39;s key event target when it is
<a name="line115"></a> * shown.  Default = true
<a name="line116"></a> * @type {boolean}
<a name="line117"></a> * @private
<a name="line118"></a> */
<a name="line119"></a>goog.ui.Menu.prototype.allowAutoFocus_ = true;
<a name="line120"></a>
<a name="line121"></a>
<a name="line122"></a>/**
<a name="line123"></a> * Whether the menu should use windows syle behavior and allow disabled menu
<a name="line124"></a> * items to be highlighted (though not selectable).  Defaults to false
<a name="line125"></a> * @type {boolean}
<a name="line126"></a> * @private
<a name="line127"></a> */
<a name="line128"></a>goog.ui.Menu.prototype.allowHighlightDisabled_ = false;
<a name="line129"></a>
<a name="line130"></a>
<a name="line131"></a>/**
<a name="line132"></a> * Returns the CSS class applied to menu elements, also used as the prefix for
<a name="line133"></a> * derived styles, if any.  Subclasses should override this method as needed.
<a name="line134"></a> * Considered protected.
<a name="line135"></a> * @return {string} The CSS class applied to menu elements.
<a name="line136"></a> * @protected
<a name="line137"></a> * @deprecated Use getRenderer().getCssClass().
<a name="line138"></a> */
<a name="line139"></a>goog.ui.Menu.prototype.getCssClass = function() {
<a name="line140"></a>  return this.getRenderer().getCssClass();
<a name="line141"></a>};
<a name="line142"></a>
<a name="line143"></a>
<a name="line144"></a>/**
<a name="line145"></a> * Returns whether the provided element is to be considered inside the menu for
<a name="line146"></a> * purposes such as dismissing the menu on an event.  This is so submenus can
<a name="line147"></a> * make use of elements outside their own DOM.
<a name="line148"></a> * @param {Element} element The element to test for.
<a name="line149"></a> * @return {boolean} Whether the provided element is to be considered inside
<a name="line150"></a> *     the menu.
<a name="line151"></a> */
<a name="line152"></a>goog.ui.Menu.prototype.containsElement = function(element) {
<a name="line153"></a>  if (this.getRenderer().containsElement(this, element)) {
<a name="line154"></a>    return true;
<a name="line155"></a>  }
<a name="line156"></a>
<a name="line157"></a>  for (var i = 0, count = this.getChildCount(); i &lt; count; i++) {
<a name="line158"></a>    var child = this.getChildAt(i);
<a name="line159"></a>    if (typeof child.containsElement == &#39;function&#39; &amp;&amp;
<a name="line160"></a>        child.containsElement(element)) {
<a name="line161"></a>      return true;
<a name="line162"></a>    }
<a name="line163"></a>  }
<a name="line164"></a>
<a name="line165"></a>  return false;
<a name="line166"></a>};
<a name="line167"></a>
<a name="line168"></a>
<a name="line169"></a>/**
<a name="line170"></a> * Adds a new menu item at the end of the menu.
<a name="line171"></a> * @param {goog.ui.MenuItem|goog.ui.MenuSeparator} item Menu item to add to
<a name="line172"></a> *     the menu.
<a name="line173"></a> * @deprecated Use {@link #addChild} instead.
<a name="line174"></a> */
<a name="line175"></a>goog.ui.Menu.prototype.addItem = function(item) {
<a name="line176"></a>  this.addChild(item, true);
<a name="line177"></a>};
<a name="line178"></a>
<a name="line179"></a>
<a name="line180"></a>/**
<a name="line181"></a> * Adds a new menu item at a specific index in the menu.
<a name="line182"></a> * @param {goog.ui.MenuItem|goog.ui.MenuSeparator} item Menu item to add to the
<a name="line183"></a> *     menu.
<a name="line184"></a> * @param {number} n Index at which to insert the menu item.
<a name="line185"></a> * @deprecated Use {@link #addChildAt} instead.
<a name="line186"></a> */
<a name="line187"></a>goog.ui.Menu.prototype.addItemAt = function(item, n) {
<a name="line188"></a>  this.addChildAt(item, n, true);
<a name="line189"></a>};
<a name="line190"></a>
<a name="line191"></a>
<a name="line192"></a>/**
<a name="line193"></a> * Removes an item from the menu and disposes of it.
<a name="line194"></a> * @param {goog.ui.MenuItem|goog.ui.MenuSeparator} item The menu item to remove.
<a name="line195"></a> * @deprecated Use {@link #removeChild} instead.
<a name="line196"></a> */
<a name="line197"></a>goog.ui.Menu.prototype.removeItem = function(item) {
<a name="line198"></a>  var removedChild = this.removeChild(item, true);
<a name="line199"></a>  if (removedChild) {
<a name="line200"></a>    removedChild.dispose();
<a name="line201"></a>  }
<a name="line202"></a>};
<a name="line203"></a>
<a name="line204"></a>
<a name="line205"></a>/**
<a name="line206"></a> * Removes a menu item at a given index in the menu and disposes of it.
<a name="line207"></a> * @param {number} n Index of item.
<a name="line208"></a> * @deprecated Use {@link #removeChildAt} instead.
<a name="line209"></a> */
<a name="line210"></a>goog.ui.Menu.prototype.removeItemAt = function(n) {
<a name="line211"></a>  var removedChild = this.removeChildAt(n, true);
<a name="line212"></a>  if (removedChild) {
<a name="line213"></a>    removedChild.dispose();
<a name="line214"></a>  }
<a name="line215"></a>};
<a name="line216"></a>
<a name="line217"></a>
<a name="line218"></a>/**
<a name="line219"></a> * Returns a reference to the menu item at a given index.
<a name="line220"></a> * @param {number} n Index of menu item.
<a name="line221"></a> * @return {goog.ui.MenuItem|goog.ui.MenuSeparator|null} Reference to the menu
<a name="line222"></a> *     item.
<a name="line223"></a> * @deprecated Use {@link #getChildAt} instead.
<a name="line224"></a> */
<a name="line225"></a>goog.ui.Menu.prototype.getItemAt = function(n) {
<a name="line226"></a>  return /** @type {goog.ui.MenuItem?} */(this.getChildAt(n));
<a name="line227"></a>};
<a name="line228"></a>
<a name="line229"></a>
<a name="line230"></a>/**
<a name="line231"></a> * Returns the number of items in the menu (including separators).
<a name="line232"></a> * @return {number} The number of items in the menu.
<a name="line233"></a> * @deprecated Use {@link #getChildCount} instead.
<a name="line234"></a> */
<a name="line235"></a>goog.ui.Menu.prototype.getItemCount = function() {
<a name="line236"></a>  return this.getChildCount();
<a name="line237"></a>};
<a name="line238"></a>
<a name="line239"></a>
<a name="line240"></a>/**
<a name="line241"></a> * Returns the menu items contained in the menu.
<a name="line242"></a> * @return {Array.&lt;goog.ui.MenuItem&gt;} An array of menu items.
<a name="line243"></a> * @deprecated Use getChildAt, forEachChild, and getChildCount.
<a name="line244"></a> */
<a name="line245"></a>goog.ui.Menu.prototype.getItems = function() {
<a name="line246"></a>  // TODO: Remove reference to getItems and instead use getChildAt,
<a name="line247"></a>  // forEachChild, and getChildCount
<a name="line248"></a>  return this.children_ || [];
<a name="line249"></a>};
<a name="line250"></a>
<a name="line251"></a>
<a name="line252"></a>/**
<a name="line253"></a> * Sets the position of the menu relative to the view port.
<a name="line254"></a> * @param {number|goog.math.Coordinate} x Left position or coordinate obj.
<a name="line255"></a> * @param {number} opt_y Top position.
<a name="line256"></a> */
<a name="line257"></a>goog.ui.Menu.prototype.setPosition = function(x, opt_y) {
<a name="line258"></a>  // NOTE: It is necessary to temporarily set the display from none, so
<a name="line259"></a>  // that the position gets set correctly.
<a name="line260"></a>  var visible = this.isVisible();
<a name="line261"></a>  if (!visible) {
<a name="line262"></a>    goog.style.showElement(this.getElement(), true);
<a name="line263"></a>  }
<a name="line264"></a>  goog.style.setPageOffset(this.getElement(), x, opt_y);
<a name="line265"></a>  if (!visible) {
<a name="line266"></a>    goog.style.showElement(this.getElement(), false);
<a name="line267"></a>  }
<a name="line268"></a>};
<a name="line269"></a>
<a name="line270"></a>
<a name="line271"></a>/**
<a name="line272"></a> * Gets the page offset of the menu, or null if the menu isn&#39;t visible
<a name="line273"></a> * @return {goog.math.Coordinate?} Object holding the x-y coordinates of the
<a name="line274"></a> *     menu or null if the menu is not visible.
<a name="line275"></a> */
<a name="line276"></a>goog.ui.Menu.prototype.getPosition = function() {
<a name="line277"></a>  return this.isVisible() ? goog.style.getPageOffset(this.getElement()) : null;
<a name="line278"></a>};
<a name="line279"></a>
<a name="line280"></a>
<a name="line281"></a>/**
<a name="line282"></a> * Sets whether the menu can automatically move focus to its key event target
<a name="line283"></a> * when it is set to visible.
<a name="line284"></a> * @param {boolean} allow Whether the menu can automatically move focus to its
<a name="line285"></a> *     key event target when it is set to visible.
<a name="line286"></a> */
<a name="line287"></a>goog.ui.Menu.prototype.setAllowAutoFocus = function(allow) {
<a name="line288"></a>  this.allowAutoFocus_ = allow;
<a name="line289"></a>  if (allow) {
<a name="line290"></a>    this.setFocusable(true);
<a name="line291"></a>  }
<a name="line292"></a>};
<a name="line293"></a>
<a name="line294"></a>
<a name="line295"></a>/**
<a name="line296"></a> * @return {boolean} Whether the menu can automatically move focus to its key
<a name="line297"></a> *     event target when it is set to visible.
<a name="line298"></a> */
<a name="line299"></a>goog.ui.Menu.prototype.getAllowAutoFocus = function() {
<a name="line300"></a>  return this.allowAutoFocus_;
<a name="line301"></a>};
<a name="line302"></a>
<a name="line303"></a>
<a name="line304"></a>/**
<a name="line305"></a> * Sets whether the menu will highlight disabled menu items or skip to the next
<a name="line306"></a> * active item.
<a name="line307"></a> * @param {boolean} allow Whether the menu will highlight disabled menu items or
<a name="line308"></a> *     skip to the next active item.
<a name="line309"></a> */
<a name="line310"></a>goog.ui.Menu.prototype.setAllowHighlightDisabled = function(allow) {
<a name="line311"></a>  this.allowHighlightDisabled_ = allow;
<a name="line312"></a>};
<a name="line313"></a>
<a name="line314"></a>
<a name="line315"></a>/**
<a name="line316"></a> * @return {boolean} Whether the menu will highlight disabled menu items or skip
<a name="line317"></a> *     to the next active item.
<a name="line318"></a> */
<a name="line319"></a>goog.ui.Menu.prototype.getAllowHighlightDisabled = function() {
<a name="line320"></a>  return this.allowHighlightDisabled_;
<a name="line321"></a>};
<a name="line322"></a>
<a name="line323"></a>
<a name="line324"></a>/** @inheritDoc */
<a name="line325"></a>goog.ui.Menu.prototype.setVisible = function(show, opt_force) {
<a name="line326"></a>  var visibilityChanged = goog.ui.Menu.superClass_.setVisible.call(this, show,
<a name="line327"></a>      opt_force);
<a name="line328"></a>  if (visibilityChanged &amp;&amp; show &amp;&amp; this.isInDocument() &amp;&amp;
<a name="line329"></a>      this.allowAutoFocus_) {
<a name="line330"></a>    this.getKeyEventTarget().focus();
<a name="line331"></a>  }
<a name="line332"></a>  return visibilityChanged;
<a name="line333"></a>};
<a name="line334"></a>
<a name="line335"></a>
<a name="line336"></a>/** @inheritDoc */
<a name="line337"></a>goog.ui.Menu.prototype.handleEnterItem = function(e) {
<a name="line338"></a>  if (this.allowAutoFocus_) {
<a name="line339"></a>    this.getKeyEventTarget().focus();
<a name="line340"></a>  }
<a name="line341"></a>
<a name="line342"></a>  return goog.ui.Menu.superClass_.handleEnterItem.call(this, e);
<a name="line343"></a>};
<a name="line344"></a>
<a name="line345"></a>
<a name="line346"></a>/**
<a name="line347"></a> * Highlights the next item that begins with the specified string.  If no
<a name="line348"></a> * (other) item begins with the given string, the selection is unchanged.
<a name="line349"></a> * @param {string} charStr The prefix to match.
<a name="line350"></a> * @return {boolean} Whether a matching prefix was found.
<a name="line351"></a> */
<a name="line352"></a>goog.ui.Menu.prototype.highlightNextPrefix = function(charStr) {
<a name="line353"></a>  var re = new RegExp(&#39;^&#39; + goog.string.regExpEscape(charStr), &#39;i&#39;);
<a name="line354"></a>  return this.highlightHelper(function(index, max) {
<a name="line355"></a>    // Index is &gt;= -1 because it is set to -1 when nothing is selected.
<a name="line356"></a>    var start = index &lt; 0 ? 0 : index;
<a name="line357"></a>    var wrapped = false;
<a name="line358"></a>
<a name="line359"></a>    // We always start looking from one after the current, because we
<a name="line360"></a>    // keep the current selection only as a last resort. This makes the
<a name="line361"></a>    // loop a little awkward in the case where there is no current
<a name="line362"></a>    // selection, as we need to stop somewhere but can&#39;t just stop
<a name="line363"></a>    // when index == start, which is why we need the &#39;wrapped&#39; flag.
<a name="line364"></a>    do {
<a name="line365"></a>      ++index;
<a name="line366"></a>      if (index == max) {
<a name="line367"></a>        index = 0;
<a name="line368"></a>        wrapped = true;
<a name="line369"></a>      }
<a name="line370"></a>      var name = this.getChildAt(index).getCaption();
<a name="line371"></a>      if (name &amp;&amp; name.match(re)) {
<a name="line372"></a>        return index;
<a name="line373"></a>      }
<a name="line374"></a>    } while (!wrapped || index != start);
<a name="line375"></a>    return null;
<a name="line376"></a>  }, this.getHighlightedIndex());
<a name="line377"></a>};
<a name="line378"></a>
<a name="line379"></a>
<a name="line380"></a>/** @inheritDoc */
<a name="line381"></a>goog.ui.Menu.prototype.canHighlightItem = function(item) {
<a name="line382"></a>  return (this.allowHighlightDisabled_ || item.isEnabled()) &amp;&amp;
<a name="line383"></a>      item.isVisible() &amp;&amp; item.isSupportedState(goog.ui.Component.State.HOVER);
<a name="line384"></a>};
</pre>


</body>
</html>
